• Prevent credential leakage by disabling redirects for tokenizer provider POST requests.
• Avoid event-loop stalls by offloading arXiv PDF writes to a worker thread.
• Move ACP reconnect-replay lifecycle into core helpers and harden cleanup/logging.

graph TD
  client["WebSocket client"] --> acp["ACP websocket endpoint"] --> ws["ws_broadcaster helpers"] --> bus["SessionEventBus"]
  tok["tokenizer_resolver"] --> http["http_client.fetch"]
  research["research/search adapter"] --> io["Threaded file write"]

Loading

The following are alternative approaches to this PR:

1. Central redirect sanitization in http_client

• ➕ Prevents auth header leakage for all callers, not just tokenizer_resolver
• ➕ Keeps redirect behavior available while stripping/partitioning sensitive headers cross-origin
• ➖ Broader behavioral change; higher regression risk across all HTTP call sites
• ➖ Requires careful rules for same-origin vs cross-origin and header allowlists

2. Async file writer (aiofiles) instead of asyncio.to_thread

• ➕ Cleaner async semantics and potentially better scalability under heavy I/O
• ➕ Makes file writes explicit/consistent across adapters
• ➖ Adds/relies on an extra dependency and requires refactoring call sites
• ➖ Still doesn’t help with other blocking library calls (e.g., arxiv client)

3. Reconnect-replay as an async context manager

• ➕ Enforces pairing of start/stop and reduces endpoint boilerplate
• ➕ Makes cleanup semantics harder to misuse in future endpoints
• ➖ More API surface change and potential churn for existing call patterns
• ➖ May be overkill for the current single primary usage

Recommendation: Keep this PR’s targeted fixes: disabling redirects for credentialed tokenizer POSTs and moving reconnect-replay lifecycle into ws_broadcaster helpers are low-churn, high-signal changes that address concrete review/security concerns. Consider a follow-up PR for the broader http_client redirect/header-sanitization approach if redirect support is needed across the codebase.

Bug fix (3) +27 / -14

agent_client_protocol.pyDelegate reconnect replay lifecycle to ws_broadcaster core helpers +12/-11

Delegate reconnect replay lifecycle to ws_broadcaster core helpers

• Replaces in-endpoint reconnect broadcaster wiring with start_reconnect_replay/stop_reconnect_replay helpers. Cleanup now relies on core logging behavior rather than suppressing teardown exceptions in the endpoint.

tldw_Server_API/app/api/v1/endpoints/agent_client_protocol.py

tokenizer_resolver.pyDisable redirects for credentialed tokenizer POSTs and log restore failures +12/-2

Disable redirects for credentialed tokenizer POSTs and log restore failures

• Sets allow_redirects=False on provider tokenizer POST requests to avoid credential leakage on redirects. Replaces silent exception suppression when restoring encoding.timeout_seconds with a warning log.

tldw_Server_API/app/core/LLM_Calls/tokenizer_resolver.py

search.pyOffload blocking PDF writes in async arXiv download adapter +3/-1

Offload blocking PDF writes in async arXiv download adapter

• Uses asyncio.to_thread to run Path.write_bytes without blocking the event loop when downloading PDFs via managed async fetch.

tldw_Server_API/app/core/Workflows/adapters/research/search.py

Refactor (1) +58 / -0

ws_broadcaster.pyAdd reconnect-replay start/stop helpers and document consumer_id usage +58/-0

Add reconnect-replay start/stop helpers and document consumer_id usage

• Adds a docstring clarifying why unique consumer_id values matter when subscribing to the event bus. Introduces start_reconnect_replay/stop_reconnect_replay helpers and logs (rather than suppresses) failures during disconnect cleanup.

tldw_Server_API/app/core/Agent_Client_Protocol/consumers/ws_broadcaster.py

Tests (3) +33 / -14

test_acp_websocket.pyTighten ACP reconnect replay cleanup test typing and update permission tier expectations +27/-11

Tighten ACP reconnect replay cleanup test typing and update permission tier expectations

• Removes redundant pytest asyncio marker (repo uses asyncio_mode=auto) and adds missing type hints to test helpers. Updates batch/individual permission tier assertions to match the hardened contract (write/modify -> individual; fallback tools -> batch).

tldw_Server_API/tests/Agent_Client_Protocol/test_acp_websocket.py

test_ws_broadcaster.pyMark ws_broadcaster tests as unit and remove redundant asyncio marker +3/-2

Mark ws_broadcaster tests as unit and remove redundant asyncio marker

• Adds module-level pytestmark=pytest.mark.unit and updates a test signature/marker usage to align with asyncio_mode=auto conventions.

tldw_Server_API/tests/Agent_Client_Protocol/test_ws_broadcaster.py

test_tokenizer_resolver_unit.pyUpdate tokenizer POST contract test for redirects disabled +3/-1

Update tokenizer POST contract test for redirects disabled

• Adjusts the mocked fetch call expectation to require allow_redirects=False for tokenizer_resolver._http_post.

tldw_Server_API/tests/Writing/test_tokenizer_resolver_unit.py

Documentation (1) +1 / -1

2026-07-04-audit-integrations-egress-remediation-plan.mdFix audit plan task ID for verification record +1/-1

Fix audit plan task ID for verification record

• Updates Stage 4 success criteria to reference the correct tracking task ID (TASK-12146).

Docs/superpowers/plans/2026-07-04-audit-integrations-egress-remediation-plan.md

Description

The new start_reconnect_replay() docstring lacks explicit Args: and Returns: sections, so
parameter meanings and the returned WSBroadcaster are not documented per the comprehensive
docstring requirement. This reduces maintainability and makes the public contract unclear.

Code

tldw_Server_API/app/core/Agent_Client_Protocol/consumers/ws_broadcaster.py[R216-223]

+    """Create and start a dedicated broadcaster that replays missed events.
+
+    Used on WebSocket reconnect: a per-connection broadcaster (unique
+    ``consumer_id`` so concurrent reconnects don't clobber each other's bus
+    subscriptions) is subscribed to *bus* and replays buffered events from
+    *from_sequence* to *send_callback*. Callers must pair this with
+    :func:`stop_reconnect_replay` on disconnect.
+    """

Evidence

Rule 380617 requires function docstrings to document parameters and return values. The added
docstring for start_reconnect_replay() provides narrative text but does not include explicit
Args:/Returns: sections for bus, conn_id, send_callback, from_sequence, or the returned
WSBroadcaster.

Rule 380617: Require comprehensive docstrings for modules, classes, and functions
tldw_Server_API/app/core/Agent_Client_Protocol/consumers/ws_broadcaster.py[209-231]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`start_reconnect_replay()` is a newly added public function but its docstring does not include the required structured documentation (at minimum `Args:` and `Returns:`).

## Issue Context
Compliance requires comprehensive docstrings for modified/new functions, including parameter documentation and return value description.

## Fix Focus Areas
- tldw_Server_API/app/core/Agent_Client_Protocol/consumers/ws_broadcaster.py[209-231]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

start_reconnect_replay() subscribes/spawns a WSBroadcaster task before replaying buffered events; if
replay (send_callback) raises, the broadcaster is never returned so the endpoint finally-block won’t
call stop_reconnect_replay(), leaving a live bus subscriber/task behind. This can accumulate under
flaky reconnects and cause memory/CPU growth over time.

Code

tldw_Server_API/app/core/Agent_Client_Protocol/consumers/ws_broadcaster.py[R224-231]

+    broadcaster = WSBroadcaster(consumer_id=f"ws_broadcaster:{conn_id}")
+    await broadcaster.start(bus)
+    await broadcaster.add_connection(
+        conn_id=conn_id,
+        send_callback=send_callback,
+        from_sequence=from_sequence,
+    )
+    return broadcaster

Evidence

The endpoint only calls stop_reconnect_replay() when reconnect_broadcaster is assigned; if
start_reconnect_replay() raises after subscribing, reconnect_broadcaster stays None and cleanup is
skipped. WSBroadcaster.start() subscribes/spawns a task, and add_connection() can raise during
replay because it awaits send_callback, so the failure window is real and results in a leaked
subscriber/task without an explicit stop().

tldw_Server_API/app/api/v1/endpoints/agent_client_protocol.py[1277-1292]
tldw_Server_API/app/api/v1/endpoints/agent_client_protocol.py[1337-1345]
tldw_Server_API/app/core/Agent_Client_Protocol/consumers/ws_broadcaster.py[149-170]
tldw_Server_API/app/core/Agent_Client_Protocol/consumers/ws_broadcaster.py[81-105]
tldw_Server_API/app/core/Agent_Client_Protocol/consumers/ws_broadcaster.py[209-231]
tldw_Server_API/app/core/Agent_Client_Protocol/consumers/replay_utils.py[16-43]
tldw_Server_API/app/core/Agent_Client_Protocol/event_bus.py[67-108]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`start_reconnect_replay()` creates a `WSBroadcaster`, calls `start()` (subscribes + creates a consume-loop task), and then calls `add_connection()` (which may replay buffered events and invoke the provided `send_callback`). If `add_connection()` (or its replay/send) raises, the helper raises before returning the broadcaster to the caller.

In `agent_client_protocol.py`, cleanup only runs when `reconnect_broadcaster` is non-`None`. Because the assignment never completes on exception, cleanup is skipped, leaking the bus subscriber entry and the background task.

### Issue Context
`WSBroadcaster.start()` subscribes to `SessionEventBus` and spawns a task; unsubscribing only happens in `WSBroadcaster.stop()`. `add_connection()` can raise because it replays buffered events by awaiting `send_callback`.

### Fix Focus Areas
- tldw_Server_API/app/core/Agent_Client_Protocol/consumers/ws_broadcaster.py[209-231]

### Recommended fix
Wrap the body of `start_reconnect_replay()` in a `try/except` so that if anything after `broadcaster.start(bus)` fails, you `await broadcaster.stop()` (best-effort) before re-raising.

Example pattern:
```py
broadcaster = WSBroadcaster(...)
try:
   await broadcaster.start(bus)
   await broadcaster.add_connection(...)
   return broadcaster
except Exception:
   with suppress(Exception):
       await broadcaster.stop()
   raise
```

(Alternative: return the broadcaster immediately after `start()` and let the caller perform `add_connection()` + cleanup, but the above keeps the new abstraction.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

The new warning logs in stop_reconnect_replay() do not include structured contextual fields (e.g.,
action, conn_id, consumer_id) as keyword arguments/bound context. This makes error logs harder
to correlate and search, especially during disconnect/teardown failures.

Code

tldw_Server_API/app/core/Agent_Client_Protocol/consumers/ws_broadcaster.py[R245-255]

+            logger.warning(
+                "Failed to remove reconnect replay connection {}: {}", conn_id, exc
+            )
+    try:
+        await broadcaster.stop()
+    except Exception as exc:
+        logger.warning(
+            "Failed to stop reconnect replay broadcaster {}: {}",
+            broadcaster.consumer_id,
+            exc,
+        )

Evidence

Rule 380623 requires contextual data in error-condition logs using loguru. The added
logger.warning(...) calls log only positional-formatted strings, without binding or passing
structured fields like action, conn_id, or consumer_id as keyword arguments.

Rule 380623: Include contextual data in error logs with loguru
tldw_Server_API/app/core/Agent_Client_Protocol/consumers/ws_broadcaster.py[241-255]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`stop_reconnect_replay()` emits `logger.warning(...)` messages without structured context fields (keyword args or `logger.bind(...)`).

## Issue Context
Compliance requires contextual identifiers/operation info in error-condition logs using loguru, ideally as structured fields for correlation and filtering.

## Fix Focus Areas
- tldw_Server_API/app/core/Agent_Client_Protocol/consumers/ws_broadcaster.py[241-255]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools